<?php
/**
 * defines interfaces for Webappkit.
 * Kits => iWakKit
 * Tools => iWakTool
 * Storage Tools => iWakStorage
 * Tests Tools ??
 * Doc Tools ??
 *
 * This file is part of Webappkit, a packages system for PHP web apps
 * @link http://webappkit.net
 * @package webappkit
 * @author J.Ducastel <nospam0@ducastel.name>
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
 */

/**
 * PHP packages, named Kits
 * Please extends base class WakKit for your kits
 */
interface iWakKit {

    /**
     * Only application kits have to really implement this.
     * Is called when a kit is asked to handle web request.
     * @return bool
     */
    public function run();

    /**
     * return kit's id
     * @return string
     */
    public function getId();

    /**
     * return kit's root filesystem path
     * @return string
     */
    public function getPath();

    /**
     * return included subkit ids
     * ids are returned relative, excluding parent kit part
     * @return array
     */
    public function listSubkits();

    /**
	 * get a subkit instance if available
	 * @access public
	 * @param string subkit id (without the parent part)
	 * @return WakKit
	 */
	function getSubkit($id);

    /**
	 * get kit tools.
	 * May filter by class
	 * @access public
	 * @param string $class if provided, will return only tools from this class
	 * @return array name=>instance
	 */
	public function & getTools($class=null);

    /**
	 * tells if a tool has its custom config
	 * @access public
	 * @param string $tool tool's name
	 * @return bool
	 */
	public function toolHasConfig($tool);
}

/**
 * kit members, named Tools
 */
interface iWakTool {
	/**
	 * factory pattern, use this method to build instances
	 * all subclasses have to implement this method
	 * because of PHP object model limitations
	 * @static
	 * @param string $kit_id parent kit id
	 * @param array $cfg configuration data, will be merged with defaults
	 * @return wakTool
	 */
	public static function toolFactory($kit_id,$cfg=array());

	/**
	 * get parent kit's id
	 * @access public
	 * @return string
	 */
	public function getKitId();

	/**
	 * get configuration data
	 * @access public
	 * @return array
	 */
	public function getCfg();

    /**
     * defaults for configuration
     */
    // protected $default_cfg=array();
}

/**
 * object instances storage interface.
 * Usually provided as Tools
 */
interface iWakStorage {

    /**
     * get an instance from storage
     * @param mixed $id instance unique id
     * @return object
     */
    public function get($id);

    /**
     * insert an object instance.
     * May update some key/id member if id is generated
     * @param object instance to save
     * @return bool
     */
	public function save(&$object);

	/**
	 * check if storage has item
	 * @param string $id instance unique id
	 * @return bool
	 */
	public function has($id);

	/**
	 * destroy/delete object into storage
	 * @param mixed $id instance unique id
	 * @return bool
	 */
	public function delete($id);

	/**
	 * search instances from an array of parameters
	 * @param array $critera search parameters
	 * @return array found instances
	 */
	public function search($criteria);

	/**
	 * get stored class name
	 * @return string
	 */
	public function getClass();

	/**
	 * get stored objects id member name
	 * @return string
	 */
	public function getIdMember();
}
